PC World Interactive 1

home *** CD-ROM | disk | FTP | other *** search

/ PC World Interactive 1 / PC World Interactive 1 - Nisan 1997.iso / nostalji / bbs / music / sbbook.arj / SBBOOK / SOURCE / DRIVERS.TXT

Wrap

Text File | 1993-12-29 | 80.4 KB | 1,964 lines

Programming the Sound Blaster Drivers Directly Creative Labs currently offers drivers that provide a level of abstraction between the hardware and the application. These drivers release the programmer from the hassles of controlling the hardware directly while still providing all the services necessary for basic playback and recording of digital voice files (VOC), playback of music files (CMF and MID), and mixer control. ---------------------------------------------------------------------- ------Programming the Digital Voice Memory Driver (CT-VOICE.DRV)------ ---------------------------------------------------------------------- The CT-VOICE driver is a loadable driver rather than a TSR. A loadable driver offers a better solution to the programmer because its loading and unloading is left to the application and not to the user. This increases the probability that the application using the driver will run the first time the user executes it. Loading the Driver ------------------ All functions in this digital voice driver are accessed as offsets from the beginning of the segment where the driver was loaded. This requires that the driver be loaded at a segment boundary. When a driver is loaded at a segment boundary, it simply means that the starting address of the driver must have an offset of zero (SEG:0000). If you are using DOS function calls to allocate memory, then this has already been done for you (interrupt 21h, function 48h). If you wish to use C's malloc() or farmalloc() calls, then you need to follow the following loading procedure. { Get driver size. Allocate memory for the driver size + 16. Save the pointer returned by malloc for freeing the memory later. Divide the pointer's offset by 16 and add it to the pointer's segment. Add one to the pointer's segment. Set the pointer's offset to zero. Open the driver file. Read the driver into the new location calculated above. Close the driver file. . . . Your program goes here. . . . Free the memory associated with the original malloc'ed pointer. } Digital Voice Playback from Conventional Memory ----------------------------------------------- The following pseudocode demonstrates voice playback from conventional memory using Creative's new API, which is available on all drivers with a version number of 3.00 or higher. { Load CT-VOICE driver. Get driver version by calling Get Parameter function with CX = 1. If driver version is greater than or equal to version written for. { Call Get Environment Settings function. Call Initialize Driver function. Set the Voice Status Word by calling Set I/O Parameter function with AX = 1. Turn on the speaker by calling Set Speaker function with AX = 1. Call Output from Conventional Memory function. . . . Call Pause Voice Output function. Call Continue Voice Output function. Call Stop Voice I/O function. . . . Monitor the Voice Status Word until finished (Voice Status Word = 0000h). Call Terminate Driver function. } Free memory used for the CT-VOICE driver. } Digital Voice Recording from Conventional Memory ------------------------------------------------ The following pseudocode demonstrates voice recording to conventional memory using Creative's new API, which is available on all drivers with a version number of 3.00 or higher. { Load CT-VOICE driver. Get driver version by calling Get Parameter function with CX = 1. If driver version is greater than or equal to version written for. { Call Get Environment Settings function. Call Initialize Driver function. Set the Voice Status Word by calling Set I/O Parameter function with AX = 1. Set the the number of channels to use by calling Set I/O Parameter function with AX = 4. Set the left channel's recording sources by calling Set I/O Parameter function with AX = 5. Set the right channel's recording sources by calling Set I/O Parameter function with AX = 6. Turn off the speaker by calling Set Speaker function with AX = 0. Call Record into Conventional Memory function. Create a VOC file header for recording. Save recording to a file. Call Stop Voice I/O function when finished. Call Terminate Driver function. } Free memory used for the CT-VOICE driver. } Digital Voice Playback from Extended Memory ------------------------------------------- The following pseudocode demonstrates voice playback from extended memory using Creative's new API, which is available on all drivers with a version number of 3.00 or higher. { Load CT-VOICE driver. Get driver version by calling Get Parameter function with CX = 1. If driver version is greater than or equal to version written for. { Call Get Environment Settings function. Check to see if HIMEM.SYS is loaded. Allocate extended memory large enough to hold file. Call Initialize Driver function. Set the Voice Status Word by calling Set I/O Parameter function with AX = 1. Load file into extended memory. Turn on the speaker by calling Set Speaker function with AX = 1. Call Output from Extended Memory function. . . . Call Pause Voice Output function. Call Continue Voice Output function. Call Stop Voice I/O function. . . . Monitor the Voice Status Word until finished (Voice Status Word = 0000h). Call Terminate Driver function. Free extended memory. } Free memory used for the CT-VOICE driver. } Digital Voice Recording from Extended Memory -------------------------------------------- The following pseudocode demonstrates voice recording to extended memory using Creative's new API, which is available on all drivers with a version number of 3.00 or higher. { Load CT-VOICE driver. Get driver version by calling Get Parameter function with CX = 1. If driver version is greater than or equal to version written for. { Call Get Environment Settings function. Check to see if HIMEM.SYS is loaded. Allocate extended memory buffer for recording into. Call Initialize Driver function. Set the Voice Status Word by calling Set I/O Parameter function with AX = 1. Set the the number of channels to use by calling Set I/O Parameter function with AX = 4. Set the left channel's recording sources by calling Set I/O Parameter function with AX = 5. Set the right channel's recording sources by calling Set I/O Parameter function with AX = 6. Turn off the speaker by calling Set Speaker function with AX = 0. Call Record into Extended Memory function. Call Stop Voice I/O function when finished. Call Terminate Driver function. Create a VOC file header for recording. Save recording to a file. Free extended memory buffer. } Free memory used for the CT-VOICE driver. } CT-VOICE Function Definitions ----------------------------- The following pseudocode demonstrates mixer functions using Creative's new API, which is available on all drivers with a version number of 3.00 or higher. < Parameters Used with Set Parameters Function > Parameter Number Description ------------------------------- 1 Voice status word address 3 Sampling rate 4 Number of channels to use for recording 5 Left channel sources for recording 6 Right channel sources for recording 7 Voice format for recording* 8 Bits per sample for recording < Parameters Used with Get and Set I/O Parameters Functions > Parameter Number Description ------------------------------- 1 Driver version 2 Card type number 3 Card name 4 Number of input channels 5 Number of output channels 6 Driver size, less embedded DMA buffer* 7 Number of I/O handles supported 8 Driver build number 9 Size of embedded DMA buffer 10 Sampling rate limits * The CT-VOICE and CTVDSK drivers now use auto-init mode, which offers higher quality audio reproduction. Auto-init mode requires a DMA buffer to record and play back digital data. To support code written for earlier drivers, a DMA buffer had to be embedded in the driver. If you wish to provide the driver with your own DMA buffer, then you can use this value to determine how much of the driver to read into memory, thus removing the DMA buffer. < Input Sources Used with Get and Set I/O Parameter Functions > parameters 5 and 6 The input sources allow you to select the recording sources for the left and right channels. Each channel is defined by one word (2 bytes). Source selection is defined as follows: D15...D8 D7 D6 D5 D4 D3 D2 D1 D0 |....| | | | | | | | | |....| | | | | | | | +---> Microphone |....| | | | | | | +--------> Microphone |....| | | | | | +-------------> CD Right |....| | | | | +------------------> CD Left |....| | | | +-----------------------> Line-In Right |....| | | +----------------------------> Line-In Left |....| | +---------------------------------> MIDI Right |....| +--------------------------------------> MIDI Left |....| |....+-------------------------------------------> Not Used +------------------------------------------------> Not Used Note: Since the microphone is a mono source, both bits (D0 and D1) should be set. When using the Sound Blaster Pro, only the Line-In, CD, and Microphone are applicable. Also, only one source may be used, and both channels of that source should be selected simultaneously. File Formats Used with Get and Set I/O Parameters Functions ----------------------------------------------------------- Only PCM file format (function 0) is supported in this text. Compression and decompression information is available in the DOS developers kit by Creative Labs. Driver Error Codes ------------------ Error Code Description 1 DOS memory allocation error 2 Another voice I/O process is currently active 3 DOS read voice file error 4 DOS write voice file error 5 DOS lseek error on voice file 6 Disk full 7 Invalid voice file format 8 Disk buffer is not allocated 9 DOS open voice file error 10 Sound card I/O error 11 Incorrect driver version 12 IRQ error 13 Not a Sound Blaster Card 14 Creative DSP copyright message error 15 DMA buffer is not allocated 16 8-bit DMA error 17 16-bit DMA error 18 Invalid I/O handle DOS Error Codes --------------- Refer to the DOS Technical Reference manual for the error code descriptions. Function definitions -------------------- * Initialize Driver (function 3) - This function initializes the driver and the sound card. Entry: The registers should be set as follows for entry to the driver: BX = 3 - function number (Initialize Driver) Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = error code - Zero if successful. Nonzero if function failed. * Set Speaker (function 4) - This function turns the DAC speaker ON or OFF. Entry: The registers should be set as follows for entry to the driver: BX = 4 - function number (Set Speaker) AX = 0 - OFF, 1 - ON Exit: No values are returned by the driver upon exit. * Terminate Driver (function 9) - This function performs some necessary housekeeping before the application is exited. Entry: The registers should be set as follows for entry to the driver: BX = 9 - function number (Terminate Driver) Exit: No values are returned by the driver upon exit. * Get Environment Settings (function 28) - This function parses the BLASTER environment string and sets the base I/O address, the interrupt number, and the DMA channel in the driver. Entry: The registers should be set as follows for entry to the driver: BX = 28 - function number (Get Environment Settings) ES:DI = far pointer to the BLASTER environment string Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = error code - Zero if successful. Nonzero if function failed. * Get Parameter (function 29) - This function returns information pertaining to the driver and the sound card. Entry: The registers should be set as follows for entry to the driver: BX = 29 - function number (Get Parameter) CX = parameter DX:AX = far pointer to parameter's value Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = error code - Zero if successful. Nonzero if function failed. * Set DMA Buffer (function 30) - This function allows the user the flexibility of providing the DMA buffer for the driver. The buffer passed to the driver must not straddle a physical page (64K) boundary. A physical page boundary can be defined as the point in memory where the most significant digit in the segment changes (in other words, 1FFF:FFFF => 2000:0000). You should also allocate an extra 16 bytes above the DMA buffer size desired so that the driver can round up to the next page boundary. A page boundary can be defined as the point where the lowest digit in the offset is zero (in other words, 1FFF:FFF0). Entry: The registers should be set as follows for entry to the driver: BX = 30 - function number (Set DMA Buffer) AX = I/O handle (0 for first file, 1 for second, ...) ES:DI = far pointer to buffer CX = 1/2 buffer size in Kbytes (for example, 32-Kbyte buffer = 16) Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = error code - Zero if successful. Nonzero if function failed. * Set I/O Parameter (function 31) - This function is a generic function for setting various parameters in the driver. The parameters that may be changed are detailed in the section, "CT-VOICE Function Definitions", earlier in this chapter. Entry: The registers should be set as follows for entry to the driver: BX = 31 - function number (Set I/O Parameter) AX = I/O handle (0 for first file, 1 for second, ...) DX = parameter type (see "CT-VOICE Function Definitions") DI:SI = parameter value Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = error code - Zero if successful. Nonzero if function failed. * Get I/O Parameter (function 32) - This function is a generic function for getting various parameters in the driver. The parameters that may be changed are detailed in "CT-VOICE Function Definitions." Entry: The registers should be set as follows for entry to the driver: BX = 32 - function number (Get I/O Parameter) AX = I/O handle (0 for first file, 1 for second, ...) DX = parameter type (see "CT-VOICE Function Definitions") ES:DI = far pointer to parameter storage Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = error code - Zero if successful. Nonzero if function failed. * Input Into Conventional Memory (function 33) - This function starts voice recording into conventional memory. Entry: The registers should be set as follows for entry to the driver: BX = 33 - function number (Input into Conventional Memory) AX = I/O handle (0 for first file, 1 for second, ...) ES:DI = far pointer to conventional memory buffer DX:CX = buffer size Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = error code - Zero if successful. Nonzero if function failed. * Input Into Extended Memory (function 34) - This function starts voice recording into extended memory. Entry: The registers should be set as follows for entry to the driver: BX = 34 - function number (Input into Extended Memory) AX = I/O handle (0 for first file, 1 for second, ...) DX = XMS handle DI:SI = offset into XMS block where data is located CX = XMS block size in Kbytes Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = error code - Zero if successful. Nonzero if function failed. * Output from Conventional Memory (function 35) - This function starts voice playback from conventional memory. Entry: The registers should be set as follows for entry to the driver: BX = 35 - function number (Output from Conventional Memory) AX = I/O handle (0 for first file, 1 for second, ...) ES:DI = far pointer to conventional memory buffer Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = error code - Zero if successful. Nonzero if function failed. * Output from Extended Memory (function 36) - This function starts voice playback from extended memory. Entry: The registers should be set as follows for entry to the driver: BX = 36 - function number (Output from Extended Memory) AX = I/O handle (0 for first file, 1 for second, ...) DX = XMS handle DI:SI = offset into XMS block where data is located Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = error code - Zero if successful. Nonzero if function failed. * Stop Voice I/O (function 37) - This function halts playback or recording. Entry: The registers should be set as follows for entry to the driver: BX = 37 - function number (Stop Voice I/O) AX = I/O handle (0 for first file, 1 for second, ...) Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = error code - Zero if successful. Nonzero if function failed. * Pause Voice Output (function 38) - This function pauses playback. Entry: The registers should be set as follows for entry to the driver: BX = 38 - function number (Stop Voice I/O) AX = I/O handle (0 for first file, 1 for second, ...) Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = error code - Zero if successful. Nonzero if function failed. * Continue Voice Output (function 39) - This function resumes currently paused playback. Entry: The registers should be set as follows for entry to the driver: BX = 39 - function number (Continue Voice Output) AX = I/O handle (0 for first file, 1 for second, ...) Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = error code - Zero if successful. Nonzero if function failed. * Break Voice Output Loop (function 40) - This function breaks out of a currently repeating loop of data and continues with the playback after the loop. Entry: The registers should be set as follows for entry to the driver: BX = 40 - function number (Break Voice Output Loop) AX = I/O handle (0 for first file, 1 for second, ...) CX = 0 - complete currently looping sample, nonzero - exit loop immediately. Exit Upon exit from the driver, the following values will be returned in the registers listed: AX = error code - Zero if successful. Nonzero if function failed. ----------------------------------------------------------------------- ------Programming the Digital Voice from Disk Driver (CTVDSK.DRV)------ ----------------------------------------------------------------------- The CTVDSK driver is a loadable driver instead of a TSR. A loadable driver offers a better solution to the programmer, because its loading and unloading is left to the application and not to the user. This increases the probability that the application using the driver will run the first time the user executes it. Loading the Driver ------------------ All functions in this digital voice driver are accessed as offsets from the beginning of the segment where the driver was loaded. This requires that the driver be loaded at a segment boundary. Loading a driver at a segment boundary simply means that the starting address of the driver must have an offset of zero (SEG:0000). If you are using DOS function calls to allocate memory, then this has already been done for you (Interrupt 21h, function 48h). If you wish to use C's malloc() or farmalloc() calls then you need to follow the following loading procedure. { Get driver size Allocate memory for the driver size + 16 Save the pointer returned by malloc for freeing the memory later Divide the pointer's offset by 16 and add it to the pointer's segment Add one to the pointer's segment Set the pointer's offset to zero Open the driver file Read the driver into the new location calculated above Close the driver file . . . Your program goes here . . . Free the memory associated with the original malloc'ed pointer } Digital Voice Playback from Disk -------------------------------- The following pseudocode demonstrates voice playback from disk using Creative's new API, which is available on all drivers with a version number of 3.00 or higher. { Load CTVDSK driver Get driver version by calling Get Parameter function with CX = 1 If driver version is greater than or equal to version written for { Call Get Environment Settings function Call Initialize Driver function Allocate memory for intermediate disk buffer Call Set Disk Buffer function Set the Voice Status Word by calling Set I/O Parameter function with CX = 1 Call Output function . . . Call Pause Voice Output function Call Continue Voice Output function Call Stop Voice I/O function . . . Call Get Error Codes function to determine if all went well Call Terminate Driver function } Free memory used for the CTVDSK driver. } Digital Voice Recording to Disk ------------------------------- The following pseudocode demonstrates voice recording using Creative's new API, which is available on all drivers with a version number of 3.00 or higher. { Load CTVDSK driver Get driver version by calling Get Parameter function with CX = 1 If driver version is greater than or equal to version written for { Call Get Environment Settings function Call Initialize Driver function Allocate memory for intermediate disk buffer Call Set Disk Buffer function Turn off speaker by calling Set Speaker function with AX = 0 Set the Voice Status Word by calling Set I/O Parameter function with CX = 1 Set the Number of Channels by calling Set I/O Parameter function with CX = 4 Set the data format type by calling Set I/O Parameter function with CX = 7 Set the bits per sample by calling Set I/O Parameter function with CX = 8 Set the sample rate by calling Set I/O Parameter function with CX = 3 Set the left input sources by calling Set I/O Parameter function with CX = 5 Set the right input sources by calling Set I/O Parameter function with CX = 6 Call Input function . . . Call Stop Voice I/O function Call Get Error Codes function to determine if all is well Call Terminate Driver function } Free memory used for the CTVDSK driver. } CTVDSK Function Definitions --------------------------- These functions should not be mixed with the API calls available before driver version 3.00. For parameter definitions please refer to the section, "CT-VOICE Function Definitions". * Set Speaker - This function turns the DAC speaker ON or OFF. Entry: The registers should be set as follows for entry to the driver: BX = 4 - function number (Set Speaker) AX = 0 - OFF, 1 - ON Exit: No values are returned by the driver upon exit. * Terminate Driver (function 9) _ This function performs some necessary housekeeping before the application is exited. Entry: The registers should be set as follows for entry to the driver: BX = 9 - function number (Terminate Driver) Exit: No values are returned by the driver upon exit. * Get Error Codes (function 14) - This function returns any errors that may have occurred during the driver's recent operation. Entry: The registers should be set as follows for entry to the driver: BX = 14 - function number (Get Error Codes) Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = driver error code DX = DOS error code * Get Environment Settings (function 26) - This function parses the BLASTER environment string and sets the base I/O address, the interrupt number, and the DMA channel in the driver. Entry: The registers should be set as follows for entry to the driver: BX = 26 - function number (Get Environment Settings) ES:DI = far pointer to the BLASTER environment string Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = error code - Zero if successful. Nonzero if function failed. * Get Parameter (function 27) - This function returns information pertaining to the driver and the sound card. Entry: The registers should be set as follows for entry to the driver: BX = 27 - function number (Get Parameter) CX = parameter DX:AX = far pointer to parameter's value Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = error code - Zero if successful. Nonzero if function failed. * Set Disk Buffer (function 28) - This function sets up an intermediate buffer for direct-to-disk playback and recording. It is not used for memory playback and recording. Entry: The registers should be set as follows for entry to the driver: BX = 28 - function number (Set Disk Buffer) SI = I/O handle (0 for first file, 1 for second, ...) DX:AX = far pointer to buffer CX = 1/2 buffer size in Kbytes (for example, 32-Kbyte buffer = 16). Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = error code - Zero if successful. Nonzero if function failed. * Set DMA Buffer (function 29) - This function allows the user the flexibility of providing the DMA buffer for the driver. The buffer passed to the driver must not straddle a physical page (64K) boundary. A physical page boundary can be defined as the point in memory where the most significant digit in the segment changes (for example, 1FFF:FFFF => 2000:0000). You should also allocate an extra 16 bytes above the DMA buffer size desired so that the driver can round up to the next page boundary. A page boundary can be defined as the point where the lowest digit in the offset is zero (for example, 1FFF:FFF0). Entry: The registers should be set as follows for entry to the driver: BX = 29 - function number (Set DMA Buffer) SI = I/O handle (0 for first file, 1 for second, ...) DX:AX = far pointer to buffer CX = 1/2 buffer size in Kbytes (for example, 32-Kbyte buffer = 16). Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = error code - Zero if successful. Nonzero if function failed. * Set I/O Parameter (function 30) - This function is a generic function for setting various parameters in the driver. The parameters that may be changed are detailed in the section, "CT-VOICE Function Definitions," earlier in this chapter." Entry: The registers should be set as follows for entry to the driver: BX = 30 - function number (Set I/O Parameter) SI = I/O handle (0 for first file, 1 for second, ...) CX = parameter type (see "CT-VOICE Function Definitions") DX:AX = parameter value Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = error code - Zero if successful. Nonzero if function failed. * Get I/O Parameter (function 31) - This function is a generic function for getting various parameters in the driver. The parameters that may be changed are detailed in the section "CT-VOICE Function Definitions". Entry: The registers should be set as follows for entry to the driver: BX = 31 - function number (Get I/O Parameter) SI = I/O handle (0 for first file, 1 for second, ...) CX = parameter type (see "CT-VOICE Function Definitions") DX:AX = far pointer to parameter storage Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = error code - Zero if successful. Nonzero if function failed. * Input (function 32) - This function starts the voice recording to the disk. Entry: The registers should be set as follows for entry to the driver: BX = 32 - function number (Input) DX = I/O handle (0 for first file, 1 for second, ...) AX = file handle of VOC file to record to Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = error code - Zero if successful. Nonzero if function failed. * Output (function 33) - This function starts the voice playback from the disk. Entry: The registers should be set as follows for entry to the driver: BX = 33 - function number (Output) DX = I/O handle (0 for first file, 1 for second, ...) AX = file handle of VOC file to play Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = error code - Zero if successful. Nonzero if function failed. * Stop Voice I/O (function 34) - This function halts playback or recording. Entry: The registers should be set as follows for entry to the driver: BX = 34 - function number (Stop Voice I/O) DX = I/O handle (0 for first file, 1 for second, ...) Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = error code - Zero if successful. Nonzero if function failed. * Pause Voice Output (function 35) - This function pauses playback. Entry: The registers should be set as follows for entry to the driver: BX = 35 - function number (Stop Voice I/O) DX = I/O handle (0 for first file, 1 for second, ...) Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = error code - Zero if successful. Nonzero if function failed. * Continue Voice Output (function 36) - This function resumes currently paused playback. Entry: The registers should be set as follows for entry to the driver: BX = 36 - function number (Continue Voice Output) DX = I/O handle (0 for first file, 1 for second, ...) Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = error code - Zero if successful. Nonzero if function failed. * Break Voice Output Loop (function 37) - This function breaks out of a currently repeating loop of data and continues with the playback after the loop. Entry: The registers should be set as follows for entry to the driver: BX = 37 - function number (Break Voice Output Loop) DX = I/O handle (0 for first file, 1 for second, ...) AX = 0 - complete currently looping sample, nonzero - exit loop immediately. Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = error code - Zero if successful. Nonzero if function failed. * Initialize Driver (function 38) - This function initializes the driver and the sound card. Entry: The registers should be set as follows for entry to the driver: BX = 38 - function number (Initialize Driver) Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = error code - Zero if successful. Nonzero if function failed. --------------------------------------------------------- ------Programming the FM Music Driver (SBFMDRV.COM)------ --------------------------------------------------------- SBFMDRV is a TSR driver that will play CMF files on the board's FM synthesizer chip(s) if you own an SB16. To use the driver you must first install it into memory, determine what interrupt it was attached to, and make all calls to the driver via that interrupt. Locating SBFMDRV ---------------- The SBFMDRV functions are invoked by calling the interrupt that was defined when the TSR was loaded. When loading, SBFMDRV will scan interrupts between 80h and BFh, choosing the first unused interrupt (0000:0000). SBFMDRV can be identified by searching for the signature string "SBFMDRV" located at offset 103h from the interrupt vector's segment (ISEG:0103h). This pseudocode illustrates how to locate SBFMDRV: while not last interrupt and SBFMDRV not found { get interrupt vector signature pointer = (interrupt vector's segment : 0103h) does signature = "SBFMDRV"? SBFMDRV = found else increment to next interrupt } Note: Function FindDvr() in file DRVRFUNC.C demonstrates this concept. Playing a CMF File ------------------ This pseudo code illustrates how to play a .CMF file. If SBFMDRV's entry interrupt is located { Call Get Driver Version If driver version is greater than or equal to version written for { Call Initialize SBFMDRV Driver Call Set Status Byte Call Reset FM Driver Load FM music file into music buffer Locate Instrument Table in file header (Use offset 06 - 07 of CMF file to locate) Call Set Instrument Table Calculate the clock rate for the driver (Use offset 0Ch - 0Dh of the CMF file) Call Set Music Clock Rate Call Play FM Music If no errors from Play FM Music function { . . . Call Pause FM Music Call Resume FM Music . . . Call Stop FM Music } Call Reset FM Driver } } SBFMDRV Function Definitions ---------------------------- The SBFMDRV driver is accessed via the INT call. All parameters are exchanged with the driver through registers. In general, the BX register contains the function number to invoke. The return value may be found in the AX register if it is a byte or word or in DX:AX if it is a double word (4 bytes). Current status of the driver may be determined by reading the Status Byte (see "Set Status Address"). Status Byte = 00h Music is not playing Status Byte = FFh Music is playing Except for the AX and DX, all registers are preserved including the CPU flag register. * Get Driver Version (0) - This function returns the driver's version number. Entry: The registers should be set as follows for entry to the driver: BX = 0 - function number (Get Driver Version) Exit: Upon exit from the driver, the following values will be returned in the registers listed: AH = Major version number AL = Minor version number * Set Status Address (function 1) - This function provides SBFMDRV with a variable to report the current status of the driver. Your application must set this value before preparing a CMF file for playback. Entry: The registers should be set as follows for entry to the driver: BX = 1 - function number (Set Status Address) DX:AX - far pointer to the MIDI status byte Exit: No values are returned by the driver upon exit. * Set Instrument Table (2) - This function provides the driver with the parameters necessary to program the FM chip(s) for the instruments used in the CMF file(s) provided to the driver. If the number of instruments defined in this table is less than the number of available music channels, then the driver reuses the instruments from the start of the table until all channels are used. The maximum number of instruments that may be defined in this table is 128. If no table is passed to the driver, a default group of 16 instruments is used. To play the CMF file correctly, you should pass the driver a pointer to the file's instrument table. This pointer may be found at offsets 06 - 07 in the file's header. For a definition of the instrument parameters, refer to offsets 24h - 33h of the Sound Blaster Instrument file (SBI) format. The instrument parameters follow the same order and definition as the SBI file. Entry: The registers should be set as follows for entry to the driver: BX = 2 - function number (Set Instrument Table) DX:AX - far pointer to the instrument table CX - number of instruments defined in the table Exit: No values are returned by the driver upon exit. * Set System Clock Rate (function 3) - This function informs the driver of the clock rate that the timer chip (channel 0) should return to after the music has finished. If this function is never called, then the driver will re-program the timer chip for the PC's standard value of 18.2 Hz. Entry: The registers should be set as follows for entry to the driver: BX = 3 - function number (Set System Clock Rate) AX = clock rate divisor (1193180 / clock frequency in Hz) Exit: No values are returned by the driver upon exit. * Set Music Clock Rate (function 4) - This function informs the driver of the clock rate which the timer chip (channel 0) should be programmed for when the music output is started (Play FM Music function). If this function is never called then the driver will program the timer chip for the default value of 96 Hz. This value should be calculated using the value found in the CMF file's offset location 0Ch - 0Dh. If you wish to change the speed of playback, you may call this function with other values. Entry: The registers should be set as follows for entry to the driver: BX = 4 - function number (Set Music Clock Rate) AX = clock rate divisor (1193180 / clock frequency in Hz) Exit: No values are returned by the driver upon exit. * Transpose Music (function 5) - This function allows transposition of the music. A positive value for the offset transposes the music to a higher key, and a negative value transposes it to a lower key. Entry: The registers should be set as follows for entry to the driver: BX = 5 - function number (Transpose Music) AX = Number of semitones to offset music by Exit: No values are returned by the driver upon exit. * Play FM Music (function 6) - This function plays the music defined in the music block of the CMF file. When the music begins, the status byte is changed to FFh, the timer chip is programmed for the clock rate set in the Set Music Clock Rate function, and the driver intercepts the timer interrupt. The music block pointer may be determined by using the value at offset 08 - 09 in the CMF file's header. Entry: The registers should be set as follows for entry to the driver: BX = 6 - function number (Play FM Music) DX:AX = far pointer to the CMF file's music block Exit: No values are returned by the driver upon exit. * Stop FM Music (function 7) - This function stops the current music output. Calling this function also sets the status byte to 00h, reprograms the timer chip for the rate set in the Set System Clock Rate function, and restores the clock's original interrupt vector. Entry: The registers should be set as follows for entry to the driver: BX = 7 - function number (Stop FM Music) Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = 0 - function succeeded, 1 - error, no music was active. * Reset FM Driver (function 8) - This function turns off the FM chips and initializes the instrument table to the 16 default instruments. If any music is active, your program must call the Stop FM Music function first. This function should always be called before you exit your program. Entry: The registers should be set as follows for entry to the driver: BX = 8 - function number (Reset FM Driver) Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = 0 - if function succeeded, 1 - error, music still active. * Pause FM Music (function 9) - This function pauses the current music output. The music status byte is not affected by this function. Entry: The registers should be set as follows for entry to the driver: BX = 9 - function number (Pause FM Music) Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = 0 - function succeeded, 1 - error, no music was active * Resume FM Music (function 10) - This function resumes the previously paused music output. The music status byte is not affected by this function. Entry: The registers should be set as follows for entry to the driver: BX = 10 - function number (Resume FM Music) Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = 0 - function succeeded, 1 - error, no music was paused * Set SYSEX Callback (function 10) - This function installs a callback function to handle System Exclusive (SysEx) commands embedded in the music stream. Upon entry to the callback function, registers ES:SI point to the next byte in the music stream after the SysEx command (F0h). The callback routine must preserve all the registers and return to the caller via a far return (RETF). If you wish to disable the callback function you must again call this function with the pointer set to NULL (0000:0000). Note: That the driver ignores SysEx commands and continues with the music block after the end SysEx command (F7). Entry: The registers should be set as follows for entry to the driver: BX = 11 - function number (Set SysEx Callback) Exit: No values are returned by the driver upon exit. ---------------------------------------------------------- ------Programming the MIDI Music Driver (SBMIDI.EXE)------ ---------------------------------------------------------- SBMIDI is a TSR driver that will play MID files on the board's OPL3 FM chip (SB Pro 2 or SB16 only) or the Wave Blaster if you own an SB16. To use the driver you must first install it into memory, determine what interrupt it was attached to, and make all calls to the driver via that interrupt. Command Line Options for SBMIDI ------------------------------- Usage: SBMIDI [/X] | [/Y] | [/U] | [/?] [/X]: /G - General MIDI. /E - Extended MIDI (default). /B - Basic MIDI. [/Y]: /1 - Sound Blaster FM Music Synthesizer (default). /2 - External Music Synthesizer. /3 - External Music Synthesizer (MPU-401 Interface if SB16). [/U]: Unload the driver. [/?]: Display this help message. Locating SBMIDI --------------- The SBMIDI functions are invoked by calling the interrupt that was defined when the TSR was loaded. When loading, SBMIDI will scan interrupts between 80h and BFh, choosing the first interrupt that is unused (0000:0000). SBMIDI can be identified by searching for the signature string "SBMIDI," located at offset 0 from the interrupt vector's segment (ISEG:0000h). This pseudocode illustrates how to locate SBMIDI: while not last interrupt and SBMIDI not found { get interrupt vector signature pointer = (interrupt vector's segment : 0000h) does signature = "SBMIDI"? SBMIDI = found else increment to next interrupt } Note: Function FindDvr() in file DRVRFUNC.C demonstrates this concept. Playing a MID File ------------------ This pseudo code illustrates how to play a .MID file. If SBMIDI's entry interrupt is located { Call Get Driver Version If driver version is greater than or equal to version written for { Call Initialize SBMIDI Driver Call Set Status Address Save original status address Load MID file into a memory buffer Call Prepare MIDI File passing the address of the buffer If no errors from Prepare MIDI file function { Call Play MIDI Music . . . Call Pause MIDI Music Call Resume MIDI Music . . . Call Stop MIDI Music Restore original status address } } } SBMIDI Function Definitions --------------------------- The SBMIDI driver is accessed via the INT call. All parameters are exchanged with the driver through registers. In general, the BX register contains the function number to invoke. The return value may be found in the AX register if it is a byte or word, or in DX:AX if it is a double word (4 bytes). Current status of the driver may be determined by reading the Status Word (see "Set Status Address"). Status Word = 0000h Music is not playing Status Word = FFFFh Music is playing Except for the AX and DX, all registers are preserved including the CPU flag register. * Get Driver Version (function 0) - This function returns the driver's version number. Entry: The registers should be set as follows for entry to the driver: BX = 0 - function number (Get Driver Version) Exit: Upon exit from the driver, the following values will be returned in the registers listed: AH = Major version number AL = Minor version number * Initialize SBMIDI Driver (function 1) - This function performs necessary initialization functions within the driver. Entry: The registers should be set as follows for entry to the driver: BX = 1 - function number (Initialize SBMIDI driver) Exit: No values are returned by the driver upon exit. * Set Channel Map (function 2) - This Function performs channel remapping. It may be used to re-route channels defined in the MIDI file to other channels in the driver. MIDI files use, essentially, three different mappings: Basic MIDI, Extended MIDI, and General MIDI. Each uses a different set of channels and a specific mapping for the percussion channel. Basic MIDI uses the last 4 channels (13_16), with channel 16 being defined as the percussion channel. Extended MIDI uses the first 10 channels (1_10), with channel 10 being defined as the percussion channel. Last, General MIDI uses all 16 channels, with channel 10 being defined as the percussion channel. The channel array passed to the driver provides the relationship between the specified channel in the MIDI file and the actual channel used by the driver. Each entry in the array is defined as follows: map[channel # in MIDI file - 1] = channel # to map to - 1 Entry: The registers should be set as follows for entry to the driver: BX = 2 - function number (Set Channel Map) DX:AX = far pointer to 16-byte channel array Exit: No values are returned by the driver upon exit. * Set Status Address (function 3) - This function provides SBMIDI with a variable to report the current status of the driver. Your application must set this value before preparing any MIDI file for playback, and it must restore the original value before exiting to DOS. Entry: The registers should be set as follows for entry to the driver: BX = 3 - function number (Set Status Address) DX:AX - far pointer to the MIDI status word (2 bytes) Exit: Upon exit from the driver, the following values will be returned in the registers listed: DX:AX - far pointer to the previous MIDI status word (2 bytes) * Prepare MIDI File (function 4) - This function passes the MIDI file's buffer to the driver and performs some premanipulation of the MIDI data. Entry: The registers should be set as follows for entry to the driver: BX = 4 - function number (Prepare MIDI file) DX:AX = far pointer to the MIDI file's buffer Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = Zero if successful. Nonzero if function failed * Play MIDI Music (function 5) - This function actually starts the music output. Note that the status word will change to FFFFh after calling this function. Entry: The registers should be set as follows for entry to the driver: BX = 5 - function number (Play MIDI Music) Exit: No values are returned by the driver upon exit. * Stop MIDI Music (function 6) - This function stops the currently playing music. Note that the status word will change to 0000h after calling this function. Entry: The registers should be set as follows for entry to the driver: BX = 6 - function number (Stop MIDI Music) Exit: No values are returned by the driver upon exit. * Pause MIDI Music (function 7) - This function pauses the currently playing music. Note that the status word doesn't change after calling this function. Entry: The registers should be set as follows for entry to the driver: BX = 7 - function number (Pause MIDI Music) Exit: No values are returned by the driver upon exit. * Resume MIDI Music (function 8) - This function resumes playback of currently paused music. Note that the status word doesn't change after calling this function. Entry: The registers should be set as follows for entry to the driver: BX = 8 - function number (Resume MIDI Music) Exit: No values are returned by the driver upon exit. --------------------------------------------------------- ------Programming the Auxiliary Driver (AUXDRV.EXE)------ --------------------------------------------------------- The Auxiliary driver is a loadable driver instead of a TSR. A loadable driver offers a better solution to the programmer, because its loading and unloading is left to the application, not to the user. This increases the probability that the application using the driver will run the first time the user executes it. Loading the Driver ------------------ All mixer functions are accessed as offsets from the beginning of the segment where the driver was loaded. This requires that the driver be loaded at a segment boundary. Loading a driver at a segment boundary simply means that the starting address of the driver must have an offset of zero (SEG:0000). If you are using DOS function calls to allocate memory, then this has already been done for you (Interrupt 21h, function 48h). If you wish to use C's malloc() or farmalloc() calls then you need to follow the following loading procedure. { Get driver size Allocate memory for the driver size + 16 Save the pointer returned by malloc for freeing the memory later Divide the pointer's offset by 16 and add it to the pointer's segment Add one to the pointer's segment Set the pointer's offset to zero Open the driver file Read the driver into the new location calculated above Close the driver file . . . Your program goes here . . . Free the memory associated with the original malloc'ed pointer } Controlling the Mixer --------------------- This pseudo code outlines the functions available for the mixer as well as some necessary functions which must be called before using the control functions. { Load Auxiliary driver Call Get Driver Version If driver version is greater than or equal to version written for { Call Get Environment Settings (SB16 only) or Call Set Base I/O Address Call Set Fade Status Word Address (necessary) Call Set Pan Status Word Address (necessary) Call Initialize Driver . . . Call Get Source Volume Call Set Source Volume Call Get Gain (SB16 only) Call Set Gain (SB16 only) Call Get Tone (SB16 only) Call Set Tone (SB16 only) Call Get AGC (SB16 only) Call Set AGC (SB16 only) Call Get Mixer Switches (SB16 only) Call Set Mixer Switches (SB16 only) . . . Call Terminate Driver } } AUXDRV Function Definitions --------------------------- The auxiliary driver controls the volume levels of the digital voice channel, the FM music synthesizer, the microphone, the line-in source, and the CD player. Additionally, if you own an SB16, you can also control the gain, the bass and treble tone controls, and the volume of the Wave Blaster if you have one. < Sources > 0 = Master volume 1 = Voice volume 2 = FM / Wave Blaster (SB16 only) volume 3 = CD volume 4 = Line-in volume 5 = Microphone volume 6 = PC speaker volume (SB16 only) < Volume Values > Volume for all the sources is represented by values from 0 to 255. This means that if you are controlling a Sound Blaster Pro (the Pro has eight volume steps for all sources except the microphone) and you wish to change the volume by one step, you must change the driver's level by 32 (256 _ 8 = 32). Since the SB16 has 32 levels, you need only change the driver's level by 8 (256 _ 32 = 8). Volume levels are always represented as a word. The lower byte defines the right channel, and the higher byte defines the left channel. If a mono source is selected, then the high byte should be set to zero. Left channel--high byte = 0 to 255 Right channel--low byte = 0 to 255 < Gain Values (SB16 only) > The gain values range from 0 to 3. Each setting represents a doubling of the sound's level. Zero represents the original signal's volume and 3 represents 8 times the original level (Volume = Volume * (2 raised to the "gain" power)). Gain values are also represented as a word. As in the volume settings, the lower byte defines the right channel, and the higher byte represents the left channel. < Tone Values (SB16 only) > Tone values range from 0 to 255. Since the SB16 has 16 settings you need to change the driver's value by 16 (256 / 16 = 16) to change the tone by one step. Tone values are also represented as a word. The lower byte defines the right channel and the higher byte defines the left channel. < Mixer Switches (SB16 only) > The mixer switches allow you to select the live "pass-through" sources as well as the recording sources for the left and right channels. These are referred to as the output and input switches, respectively. Each channel is defined by one word (2 bytes). The switches are defined as follows: D15...D8 D7 D6 D5 D4 D3 D2 D1 D0 |....| | | | | | | | | |....| | | | | | | | +---> Microphone |....| | | | | | | +--------> Microphone |....| | | | | | +-------------> CD Right |....| | | | | +------------------> CD Left |....| | | | +-----------------------> Line-In Right |....| | | +----------------------------> Line-In Left |....| | +---------------------------------> MIDI Right |....| +--------------------------------------> MIDI Left |....| |....+-------------------------------------------> Not Used +------------------------------------------------> Not Used Note: Since the microphone is a mono source, both bits (D0 and D1) should be set. When using the Sound Blaster Pro, only the Line-In, CD, and Microphone are applicable. Also, only one source may be used, and both channels of that source should be selected simultaneously. * Get Version Number (function 0) - Gets the version number of the auxiliary driver. Entry: The registers should be set as follows for entry to the driver: BX = 0 - function number (Get Version Number) Exit: Upon exit from the driver, the following values will be returned in the registers listed: AH = Major version number AL = Minor version number * Set Base I/O Address (function 1) - This function identifies the card's location so the mixer chip may be accessed. Entry: The registers should be set as follows for entry to the driver: BX = 1 - function number (Set Base I/O Address) AX = Base I/O Address Exit: No values are returned by the driver upon exit. * Set Address of Fade Status Word (function 2) - This function is used to set up a fade status word necessary for the driver to operate properly. The fade and pan functions are considered advanced and too specialized to be covered in this text. This function must be called even though the fade functions are not used. Entry: The registers should be set as follows for entry to the driver: BX = 2 - function number (Set Address of Fade Status Word) ES:DI = far pointer to the fade status word Exit: No values are returned by the driver upon exit. * Set Address of Pan Status Word (function 3) - This function is used to set up a pan status word necessary for the driver to operate properly. The fade and pan functions are considered advanced and too specialized to be covered in this text. This function must be called even though the pan functions are not used. Entry: The registers should be set as follows for entry to the driver: BX = 3 - function number (Set Address of Pan Status Word) ES:DI = far pointer to the pan status word Exit: No values are returned by the driver upon exit. * Initialize Driver (function 4) - Performs some necessary initialization functions before the driver may be used. Entry: The registers should be set as follows for entry to the driver: BX = 4 - function number (Initialize Driver) Exit: No values are returned by the driver upon exit. * Terminate Driver (function 5) - Performs some necessary housekeeping functions before the application is terminated. Entry: The registers should be set as follows for entry to the driver: BX = 5 - function number (Terminate Driver) Exit: No values are returned by the driver upon exit. * Set Volume (function 6) - Sets the volume level of the specified source. Entry: The registers should be set as follows for entry to the driver: BX = 6 - function number (Set Volume) AX = Source (see "AUXDRV Function Definitions") DX = Level (see "AUXDRV Function Definitions") Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = Zero if successful. Nonzero if function failed * Get Volume (function 7) - Reads the volume level of the specified source. Entry: The registers should be set as follows for entry to the driver: BX = 7 - function number (Get Volume) AX = Source (see "AUXDRV Function Definitions") Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = Level (see "AUXDRV Function Definitions") * Set Gain (function 21) - Sets the gain of the input or output stage. Set Gain is only available on the SB16. Entry: The registers should be set as follows for entry to the driver: BX = 21 - function number (Set Gain) AX = 0 - input stage, 1 - output stage DX = Gain (see "AUXDRV Function Definitions") Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = Zero if successful. Nonzero if function failed * Get Gain (function 22) - Reads the gain of either the input or the output stage. Get Gain is only available on the SB16. Entry: The registers should be set as follows for entry to the driver: BX = 22 - function number (Get Gain) AX = 0 - input stage, 1 - output stage Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = Gain (see "AUXDRV Function Definitions") * Set Tone (function 23) - Sets the treble or bass tone level. Set Tone is only available on the SB16. Entry: The registers should be set as follows for entry to the driver: BX = 23 - function number (Set Tone) AX = 0 - Treble, 1 - Bass DX = Level (see "AUXDRV Function Definitions") Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = Zero if successful. Nonzero if function failed * Get Tone (function 24) - Reads the treble or bass level. Get Tone is only available on the SB16. Entry: The registers should be set as follows for entry to the driver: BX = 24 - function number (Get Tone) AX = 0 - Treble, 1 - Bass Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = Level (see "AUXDRV Function Definitions") * Set AGC (function 25) - This function will turn the AGC (Automatic Gain Control) on or off. Set AGC is only available on the SB16. Entry: The registers should be set as follows for entry to the driver: BX = 25 - function number (Set AGC) AX = 0 - OFF, 1 - ON Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = Zero if successful. Nonzero if function failed * Get AGC (function 26) - This function will read the AGC (Automatic Gain Control) state. Get AGC is only available on the SB16. Entry: The registers should be set as follows for entry to the driver: BX = 26 - function number (Get AGC) Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = State (0 - OFF, 1 - ON) * Set Mixer Switches (function 27) - This function sets the input and output switches in the mixer. Set Mixer Switches is only available on the SB16. Entry: The registers should be set as follows for entry to the driver: BX = 27 - function number (Set Mixer Switches) CX = 0 - input switches, 1 - output switches DX = Left channel switches (see "AUXDRV Function Definitions") AX = Right channel switches (see "AUXDRV Function Definitions") Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = Zero if successful. Nonzero if function failed * Get Mixer Switches (function 28) - This function reads the input and output switches in the mixer. Get Mixer Switches is only available on the SB16. Entry: The registers should be set as follows for entry to the driver: BX = 28 - function number (Get Mixer Switches) CX = 0 - input switches, 1 - output switches Exit: Upon exit from the driver, the following values will be returned in the registers listed: DX = Left channel switches (see "AUXDRV Function Definitions") AX = Right channel switches (see "AUXDRV Function Definitions") * Get Environment Settings (function 29) - This function parses the BLASTER environment string and sets the base I/O address variable in the driver. Entry: The registers should be set as follows for entry to the driver: BX = 29 - function number (Get Environment Settings) ES:DI = far pointer to the BLASTER environment string Exit: Upon exit from the driver, the following values will be returned in the registers listed: AX = Zero if successful. Nonzero if function failed ------------------------------------------------------------------------------ For more information on Creative Labs drivers, libraries, and low level register information, contact Creative Labs Customer Service and ask for the 2nd Edition of the DOS Developer's Kit.